javax.realtime
Class AsyncEventHandler

java.lang.Object
  javax.realtime.AsyncEventHandler

All Implemented Interfaces:

java.lang.Runnable, Schedulable

Direct Known Subclasses:

BoundAsyncEventHandler, BridgeObserver

public class AsyncEventHandler

extends java.lang.Object

implements Schedulable

An asychronous event handler encapsulates code that gets run at some time after an AsyncEvent occurs.

It is essentially a java.lang.Runnable with a set of parameter objects, making it very much like a RealtimeThread. The expectation is that there may be thousands of events, with corresponding handlers, averaging about one handler per event. The number of unblocked (i.e., scheduled) handlers is expected to be relatively small.

It is guaranteed that multiple firings of an event handler will be serialized. It is also guaranteed that (unless the handler explicitly chooses otherwise) for each firing of the handler, there will be one execution of the handleAsyncEvent() method.

Instances of AsyncEventHandler with a release parameter of type SporadicParameters have a list of release times which correspond to execution times of AsyncEvent.fire(). The minimum interarrival time specified in SporadicParameters is enforced as defined there. Unless the handler explicitly chooses otherwise there will be one execution of the code in handleAsyncEvent() for each entry in the list. The i-th execution of handleAsyncEvent() will be released for scheduling at the time of the i-th entry in the list.

There is no restriction on what handlers may do. They may run for a long or short time, and they may block. (Note: blocked handlers may hold system resources.)

Normally, handlers are bound to an execution context dynamically, when their AsyncEvent occurs. This can introduce a (small) time penalty. For critical handlers that can not afford the expense, and where this penalty is a problem, use a BoundAsyncEventHandler.

The semantics for memory areas that were defined for realtime threads apply in the same way to instances of AsyncEventHandler. They may inherit a scope stack when they are created, and the single parent rule applies to the use of memory scopes for instances of AsyncEventHandler just as it does in realtime threads.

Field Summary

protected java.lang.Runnable	logic This object's logic
protected MemoryArea	memoryArea This object's memory area
protected MemoryParameters	memoryParameters This object's memory parameters
protected boolean	nonheap Is does this run without a heap?
protected int	pendingFireCount This object's pending fire count
protected ProcessingGroupParameters	processingGroup This object's processing group parameters
protected ReleaseParameters	releaseParameters The release parameters
protected Scheduler	scheduler This object's scheduler
protected SchedulingParameters	schedulingParameters The scheduling parameters

Constructor Summary

AsyncEventHandler()
Create a handler whose SchedulingParameters are inherited from the current thread and does not have either ReleaseParameters or MemoryParameters.

AsyncEventHandler(boolean nonheap)
Create a handler whose parameters are inherited from the current thread, if it is a RealtimeThread, or null otherwise.

AsyncEventHandler(boolean nonheap, java.lang.Runnable logic)
Create a handler whose parameters are inherited from the current thread, if it is a RealtimeThread, or null otherwise.

AsyncEventHandler(java.lang.Runnable logic)
Create a handler whose SchedulingParameters are inherited from the current thread and does not have either ReleaseParameters or MemoryParameters.

AsyncEventHandler(SchedulingParameters schedulingParameters, ReleaseParameters releaseParameters, MemoryParameters memoryParameters, MemoryArea memoryArea, ProcessingGroupParameters processingGroup, boolean nonheap, java.lang.Runnable logic)
Create a handler with the specified parameters.

Method Summary

boolean	addIfFeasible() Add to the feasibility of the associated scheduler if the resulting feasibility is schedulable.
boolean	addToFeasibility() Inform the scheduler and cooperating facilities that the resource demands (as expressed in the associated instances of SchedulingParameters, ReleaseParameters, MemoryParameters, and ProcessingGroupParameters) of this instance of Schedulable will be considered in the feasibility analysis of the associated Scheduler until further notice.
protected int	getAndClearPendingFireCount() Atomically set to zero the number of pending executions of this handler and return the value from before it was cleared.
protected int	getAndDecrementPendingFireCount() Atomically decrements the number of pending executions of this handler (if it was non-zero) and returns the value from before the decrement.
protected int	getAndIncrementPendingFireCount() Atomically increments the number of pending executions of this handler and returns the value from before the increment.
MemoryArea	getMemoryArea() Get the current memory area.
MemoryParameters	getMemoryParameters() Get this object'MemoryParameters.
protected int	getPendingFireCount()
ProcessingGroupParameters	getProcessingGroupParameters()
ReleaseParameters	getReleaseParameters() Get the release parameters associated with this handler.
Scheduler	getScheduler() Return the Scheduler for this handler.
SchedulingParameters	getSchedulingParameters() Returns a reference to the scheduling parameters object.
void	handleAsyncEvent() If this handler was constructed using a separate Runnable object, then that Runnable object's run() method is called.
boolean	removeFromFeasibility() Not currently implemented
void	run() Not currently implemented
boolean	setIfFeasible(ReleaseParameters release, MemoryParameters memoryParameters) Not currently implemented
void	setMemoryParameters(MemoryParameters memoryParameters) Set the MemoryParameters of this schedulable object.
boolean	setMemoryParametersIfFeasible(MemoryParameters memory) Not currently implemented
void	setProcessingGroupParameters(ProcessingGroupParameters processingGroup) Set the ProcessingGroupParameters of this schedulable object.
boolean	setProcessingGroupParametersIfFeasible(ProcessingGroupParameters groupParameters) Not currently implemented
void	setReleaseParameters(ReleaseParameters releaseParameters) Set the ReleaseParameters of this object
boolean	setReleaseParametersIfFeasible(ReleaseParameters releaseParameters) Not currently implemented
void	setScheduler(Scheduler scheduler) Set the Scheduler of this object
void	setScheduler(Scheduler scheduler, SchedulingParameters schedulingParameters, ReleaseParameters releaseParameters, MemoryParameters memoryParameters, ProcessingGroupParameters processingGroup) Set the Scheduler and associated parameters of this object
void	setSchedulingParameters(SchedulingParameters schedulingParameters) Set the SchedulingParameters of this object
boolean	setSchedulingParametersIfFeasible(SchedulingParameters schedulingParameters) Not currently implemented

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

schedulingParameters

protected SchedulingParameters schedulingParameters

The scheduling parameters

releaseParameters

protected ReleaseParameters releaseParameters

The release parameters

memoryParameters

protected MemoryParameters memoryParameters

This object's memory parameters

memoryArea

protected MemoryArea memoryArea

This object's memory area

processingGroup

protected ProcessingGroupParameters processingGroup

This object's processing group parameters

logic

protected java.lang.Runnable logic

This object's logic

scheduler

protected Scheduler scheduler

This object's scheduler

nonheap

protected boolean nonheap

Is does this run without a heap?

pendingFireCount

protected int pendingFireCount

This object's pending fire count

Constructor Detail

AsyncEventHandler

public AsyncEventHandler()

Create a handler whose SchedulingParameters are inherited from the current thread and does not have either ReleaseParameters or MemoryParameters.

AsyncEventHandler

public AsyncEventHandler(boolean nonheap)
                  throws java.lang.IllegalArgumentException

Create a handler whose parameters are inherited from the current thread, if it is a RealtimeThread, or null otherwise.

Parameters:

nonheap - A flag meaning, when true, that this will have characteristics identical to a NoHeapRealtimeThread. A false value means that this will have characteristics identical to a RealtimeThread. If true and the current thread is not a NoHeapRealtimeThread or a RealtimeThread executing within a ScopedMemory or ImmortalMemory scope then an IllegalArgumentException is thrown.

AsyncEventHandler

public AsyncEventHandler(boolean nonheap,
                         java.lang.Runnable logic)
                  throws java.lang.IllegalArgumentException

Create a handler whose parameters are inherited from the current thread, if it is a RealtimeThread, or null otherwise.

Parameters:

nonheap - A flag meaning, when true, that this will have characteristics identical to a NoHeapRealtimeThread. A false value means this will have characteristics identical to a RealtimeThread. If true and the current thread is not a NoHeapRealtimeThread or a RealtimeThread executing within a ScopedMemory or ImmortalMemory scope then an IllegalArgumentException is thrown

logic - The java.lang.Runnable object whose run is executed by handleAsyncEvent.

AsyncEventHandler

public AsyncEventHandler(java.lang.Runnable logic)

Create a handler whose SchedulingParameters are inherited from the current thread and does not have either ReleaseParameters or MemoryParameters.

Parameters:

logic - The java.lang.Runnable object whose run() is executed by handleAsyncEvent().

AsyncEventHandler

public AsyncEventHandler(SchedulingParameters schedulingParameters,
                         ReleaseParameters releaseParameters,
                         MemoryParameters memoryParameters,
                         MemoryArea memoryArea,
                         ProcessingGroupParameters processingGroup,
                         boolean nonheap,
                         java.lang.Runnable logic)
                  throws java.lang.IllegalArgumentException

Create a handler with the specified parameters.

Parameters:

schedulingParameters - A SchedulingParameters of the current thread.

releaseParameters - A ReleaseParameters object which will be associated with the constructed instance of this. If null this will have no ReleaseParameters.

memoryParameters - A MemoryParameters object which will be associated with the constructed instace of this. If null this will have no MemoryParameters.

memoryArea - The MemoryArea for this AsyncEventHandler. If null, inherit the current memory area at the time of construction. The initial memory area must be a reference to a ScopedMemory or ImmortalMemory object if noheap is true.

processingGroup - A ProcessingGroupParameters object to which this will be associated. If null this will not be associated with any processing group.

nonheap - A flag meaning, when true, that this will have characteristics identical to a NoHeapRealtimeThread.

logic - The java.lang.Runnable object whose run() is executed by handleAsyncEvent().

Throws:

IllegalArgumentException - if the initial memory area is in heap memory, and the noheap parameter is true.

java.lang.IllegalArgumentException

Method Detail

addIfFeasible

public boolean addIfFeasible()

Add to the feasibility of the associated scheduler if the resulting feasibility is schedulable.

Not currently implemented

Returns:

If successful return true, if not return false. If there is no assigned scheduler false is returned.

addToFeasibility

public boolean addToFeasibility()

Inform the scheduler and cooperating facilities that the resource demands (as expressed in the associated instances of SchedulingParameters, ReleaseParameters, MemoryParameters, and ProcessingGroupParameters) of this instance of Schedulable will be considered in the feasibility analysis of the associated Scheduler until further notice. Whether the resulting system is feasible or not, the addition is completed.

Not currently implemented

Specified by:

addToFeasibility in interface Schedulable

Returns:

true if the resulting system is feasible.

getAndClearPendingFireCount

protected final int getAndClearPendingFireCount()

Atomically set to zero the number of pending executions of this handler and return the value from before it was cleared. This is used in handlers that can handle multiple firings and that want to collapse them together. The general form is:
public void handleAsyncEvent() {
int fireCount = getAndClearPendingFireCount();
... handle the events ...
}

Returns:

The pending fire count.

getAndDecrementPendingFireCount

protected int getAndDecrementPendingFireCount()

Atomically decrements the number of pending executions of this handler (if it was non-zero) and returns the value from before the decrement. This can be used in the handleAsyncEvent() method in this form to handle multiple firings:
public void handleAsyncEvent() {
int fireCount = getAndDecrementPendingFireCount();
... handle the events ...
}
The construction is necessary only in the case where one wishes to avoid the setup costs since the framework guarantees that handleAsyncEvent() will be invoked the appropriate number of times.

Returns:

The pending fire count.

getAndIncrementPendingFireCount

protected int getAndIncrementPendingFireCount()

Atomically increments the number of pending executions of this handler and returns the value from before the increment. The handleAsyncEvent() method does not need to do this, since the surrounding framework guarantees that the handler will be re-executed the appropriate number of times. It is only of value when there is a common setup code that is expensive.

Returns:

The pending fire count.

getMemoryArea

public MemoryArea getMemoryArea()

Get the current memory area.

Returns:

The current memory area in which allocations occur.

getMemoryParameters

public MemoryParameters getMemoryParameters()

Get this object'MemoryParameters.

Specified by:

getMemoryParameters in interface Schedulable

Returns:

the memory parameters

getPendingFireCount

protected final int getPendingFireCount()

Returns:

pending fire count

getProcessingGroupParameters

public ProcessingGroupParameters getProcessingGroupParameters()

Specified by:

getProcessingGroupParameters in interface Schedulable

Returns:

the ProcessingGroupParameters of this object

getReleaseParameters

public ReleaseParameters getReleaseParameters()

Get the release parameters associated with this handler.

Specified by:

getReleaseParameters in interface Schedulable

Returns:

The ReleaseParameters object associated with this.

getScheduler

public Scheduler getScheduler()

Return the Scheduler for this handler.

Specified by:

getScheduler in interface Schedulable

Returns:

The instance of Scheduler managing this.

getSchedulingParameters

public SchedulingParameters getSchedulingParameters()

Returns a reference to the scheduling parameters object.

Specified by:

getSchedulingParameters in interface Schedulable

Returns:

The SchedulingParameters object associated with this.

handleAsyncEvent

public void handleAsyncEvent()

If this handler was constructed using a separate Runnable object, then that Runnable object's run() method is called. This method will be invoked repeatedly while fireCount is greater than zero.

removeFromFeasibility

public boolean removeFromFeasibility()

Not currently implemented

Specified by:

removeFromFeasibility in interface Schedulable

Returns:

true if the resulting system is feasible.

run

public final void run()

Not currently implemented

Specified by:

run in interface java.lang.Runnable

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             MemoryParameters memoryParameters)

Not currently implemented

Parameters:

release -

memoryParameters -

Returns:

true if the resulting system is feasible.

setMemoryParameters

public void setMemoryParameters(MemoryParameters memoryParameters)

Description copied from interface: Schedulable

Set the MemoryParameters of this schedulable object.

Specified by:

setMemoryParameters in interface Schedulable

Parameters:

memoryParameters -

setMemoryParametersIfFeasible

public boolean setMemoryParametersIfFeasible(MemoryParameters memory)

Not currently implemented

Specified by:

setMemoryParametersIfFeasible in interface Schedulable

Parameters:

memory -

Returns:

true if the resulting system is feasible.

setProcessingGroupParameters

public void setProcessingGroupParameters(ProcessingGroupParameters processingGroup)

Description copied from interface: Schedulable

Set the ProcessingGroupParameters of this schedulable object.

Specified by:

setProcessingGroupParameters in interface Schedulable

Parameters:

processingGroup -

setProcessingGroupParametersIfFeasible

public boolean setProcessingGroupParametersIfFeasible(ProcessingGroupParameters groupParameters)

Not currently implemented

Specified by:

setProcessingGroupParametersIfFeasible in interface Schedulable

Parameters:

groupParameters -

Returns:

true if the resulting system is feasible.

setReleaseParameters

public void setReleaseParameters(ReleaseParameters releaseParameters)

Description copied from interface: Schedulable

Set the ReleaseParameters of this object

Specified by:

setReleaseParameters in interface Schedulable

Parameters:

releaseParameters -

setReleaseParametersIfFeasible

public boolean setReleaseParametersIfFeasible(ReleaseParameters releaseParameters)

Not currently implemented

Specified by:

setReleaseParametersIfFeasible in interface Schedulable

Parameters:

releaseParameters -

Returns:

true if the resulting system is feasible.

setScheduler

public void setScheduler(Scheduler scheduler)
                  throws java.lang.IllegalThreadStateException

Description copied from interface: Schedulable

Set the Scheduler of this object

Specified by:

setScheduler in interface Schedulable

Parameters:

scheduler -

Throws:

IllegalThreadStateException

java.lang.IllegalThreadStateException

setScheduler

public void setScheduler(Scheduler scheduler,
                         SchedulingParameters schedulingParameters,
                         ReleaseParameters releaseParameters,
                         MemoryParameters memoryParameters,
                         ProcessingGroupParameters processingGroup)
                  throws java.lang.IllegalThreadStateException

Description copied from interface: Schedulable

Set the Scheduler and associated parameters of this object

Specified by:

setScheduler in interface Schedulable

Parameters:

scheduler -

schedulingParameters -

releaseParameters -

memoryParameters -

processingGroup -

Throws:

java.lang.IllegalThreadStateException

setSchedulingParametersIfFeasible

public boolean setSchedulingParametersIfFeasible(SchedulingParameters schedulingParameters)

Not currently implemented

Specified by:

setSchedulingParametersIfFeasible in interface Schedulable

Parameters:

schedulingParameters - the given SchedulingParameters

Returns:

true if the resulting system is feasible.

setSchedulingParameters

public void setSchedulingParameters(SchedulingParameters schedulingParameters)

Description copied from interface: Schedulable

Set the SchedulingParameters of this object

Specified by:

setSchedulingParameters in interface Schedulable

Parameters:

schedulingParameters -